home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 23 / CU Amiga - Super CD-ROM 23 (June 1998).iso / CUCD / Online / AMarquee / include / Session.h
Encoding:
C/C++ Source or Header  |  1998-02-20  |  10.4 KB  |  323 lines
  1. #ifndef SESSION_H
  2. #define SESSION_H
  3.  
  4. #include <clib/AMarquee_protos.h>
  5. #include <pragmas/AMarquee_pragmas.h>
  6. #include <libraries/AMarquee.h>
  7.  
  8. // class name:  Session
  9. // requires:    amarquee.library v47+  (you must OpenLibrary() this BEFORE using this class!)
  10. //
  11. // This class is a C++ wrapper for the AMarquee client API.
  12. // Everything here should be pretty self-explanatory, as
  13. // almost every method in this class has a one-to-one 
  14. // correspondence with a similarly named amarquee.library 
  15. // C function.
  16. //
  17. // See amarquee.guide/Using AMarquee/API for a description
  18. // of what all the methods do.
  19. //
  20. // NOTE:  I haven't run-tested this code, as I don't have
  21. //        a C++ compiler for my Amiga.  It does compile on
  22. //        other systems (with the C back-end stubbed out), though, 
  23. //        and it's simple enough that I don't expect any problems
  24. //        with it.  Please email me if you find any!
  25. //        (jfriesne@ucsd.edu)
  26. //
  27.  
  28. // This exception is thrown by the constructor if the QNewSession()
  29. // call fails (e.g. out of memory or the TCP connection failed)
  30. class SessionCreationFailedException
  31. {
  32. public:
  33.   SessionCreationFailedException() {}
  34.   ~SessionCreationFailedException() {}
  35.  
  36. private:
  37.   // err, nothing to store here!
  38. };
  39.  
  40. // NOTE:  Don't forget to OpenLibrary("amarquee.library", 47L) before
  41. //        instantiating any Sessions!  (and of course be sure to
  42. //        CloseLibrary(AMarqueeBase) before you exit...)
  43. //
  44. class Session {
  45. public:
  46.   // Pseudo-constructor methods:  These can be used as an
  47.   // alternative to the "real" constructor below, if you don't want
  48.   // to worry about catching SessionCreationFailedExceptions.
  49.   // Each method will return a either valid Session object, which
  50.   // the calling code is then responsible for deleting, or NULL 
  51.   // to indicate failure.
  52.   static inline Session * newSession(const char * hostName, LONG port, const char * progName) throw();
  53.   static inline Session * newSessionAsync(const char * hostName, LONG port, const char * progName) throw();
  54.   static inline Session * newHostSession(const char * hostName, LONG & port, const char * progName) throw();
  55.   static inline Session * newServerSession(const char * whichHosts, const char * whichProgNames) throw();
  56.  
  57.   // Constructor:  If you want to use a Real Constructor, here's one.
  58.   // This constructor calls either QNewSession() or QNewSessionAsync(), 
  59.   // depending on the (async) parameter.
  60.   // If the internal QNewSession() call fails, a SessionCreationFailedException will be thrown.
  61.   inline Session(const char * hostName, LONG port, const char * progName, BOOL async = FALSE) throw(SessionCreationFailedException);
  62.   
  63.   // Destructor:  You MUST delete every Session you create, or it's crash city!
  64.   inline ~Session() throw();
  65.  
  66.   // Accessor:  Wait() on this MsgPort for QMessages
  67.   inline struct MsgPort * getMsgPort() const throw();
  68.   
  69.   // Operations:  Each of these queues up a transaction.
  70.   // Each returns a positive ID number on success, or 0L on failure.
  71.   
  72.   inline LONG getOp(const char * wildpath, LONG maxBytes=-1L) throw();
  73.   inline LONG setOp(const char * path, const void * buffer, ULONG bufferLength) throw();
  74.  
  75.   inline LONG subscribeOp(const char * wildpath, LONG maxBytes=-1L) throw();
  76.   inline LONG clearSubscriptionsOp(LONG which=0L) throw();
  77.   inline LONG getAndSubscribeOp(const char * wildpath, LONG maxBytes=-1L) throw();
  78.  
  79.   inline LONG streamOp(const char * path, const void * buffer, ULONG bufferLength) throw();  
  80.   inline LONG messageOp(const char * hosts, const void * buffer, ULONG bufferLength) throw();
  81.  
  82.   inline LONG renameOp(const char * path, const char * label) throw();
  83.   inline LONG deleteOp(const char * wildpath) throw();
  84.  
  85.   inline LONG pingOp() throw();
  86.   inline LONG infoOp() throw();
  87.   inline LONG debugOp(const char * string) throw();
  88.  
  89.   inline LONG setAccessOp(const char * newAccess) throw();
  90.   inline LONG setMessageAccessOp(const char * newAccess, LONG maxBytes=-1L) throw();
  91.  
  92.   inline LONG requestPrivilegesOp(ULONG privBits) throw();
  93.   inline LONG releasePrivilegesOp(ULONG privBits) throw();
  94.  
  95.   inline LONG killClientsOp(const char * hosts) throw();
  96.   inline LONG setParameterOp(const char * paramName, const char * newValue) throw();
  97.   inline LONG getParameterOp(const char * paramName) throw();
  98.   inline LONG sysMessageOp(const char * hosts, const char * message) throw();
  99.  
  100.   // Call this when you've queued all your transactions.
  101.   // It sends them on their merry way.
  102.   inline LONG go(ULONG flags=0L) throw();
  103.  
  104.   // Call this function to free QMessage's you received 
  105.   // from this->getMsgPort()->GetMsg()
  106.   inline void freeQMessage(struct QMessage * qmsg) throw();
  107.  
  108.   // These return the approximate current status of outgoing queue.
  109.   // Note that they aren't thread safe, so the results you get may
  110.   // be inaccurate.
  111.   inline ULONG getNumQueuedPackets() const throw();
  112.   inline ULONG getNumQueuedBytes() const throw();
  113.  
  114.   // Returns an ASCII description of the passed-in error code.
  115.   static inline const char * getErrorName(LONG error) throw();
  116.  
  117.   /* Introduced for v1.47, to support sharing QSessions between threads */
  118.   inline BOOL detachSession(ULONG flags=0L) throw();
  119.   inline BOOL reattachSession(ULONG flags=0L) throw();
  120.     
  121. private:
  122.   inline Session(struct QSession *) throw();  // for our private use
  123.  
  124.   // Purposely unimplemented and inaccessible
  125.   Session();
  126.   Session(const Session &);    // disallow copy constructor
  127.   Session& operator =(const Session &); // disallow assignment
  128.  
  129.   struct QSession * session;
  130. };
  131.  
  132. ////////////////////////////////////////////////////////////////////////
  133. //
  134. // CODE IMPLEMENTATION:  You shouldn't need to look below this line!
  135. //
  136. ////////////////////////////////////////////////////////////////////////
  137.  
  138. inline Session::Session(struct QSession * s) throw()  
  139. {
  140.   session = s;
  141. }
  142.  
  143. inline Session * Session::newSession(const char * hostName, LONG port, const char * progName) throw()
  144. {
  145.   struct QSession * s = QNewSession((char *)hostName, port, (char *)progName);
  146.   return(s ? new Session(s) : NULL);
  147. }
  148.  
  149. inline Session * Session::newSessionAsync(const char * hostName, LONG port, const char * progName) throw()
  150. {
  151.   struct QSession * s = QNewSessionAsync((char *) hostName, port, (char *)progName);
  152.   return(s ? new Session(s) : NULL);
  153. }
  154.  
  155. inline Session * Session::newHostSession(const char * hostName, LONG & port, const char * progName) throw()
  156. {
  157.   struct QSession * s = QNewHostSession((char *) hostName, &port, (char *) progName);
  158.   return(s ? new Session(s) : NULL);
  159. }
  160.  
  161. inline Session * Session::newServerSession(const char * whichHosts, const char * whichProgNames) throw()
  162. {
  163.   struct QSession * s = QNewServerSession((char *) whichHosts, (char *) whichProgNames);
  164.   return(s ? new Session(s) : NULL);
  165. }
  166.  
  167. inline Session::Session(const char * h, LONG p, const char * n, BOOL a) throw(SessionCreationFailedException)  
  168. {
  169.   session = a ? QNewSessionAsync((char *)h,p,(char *)n) : QNewSession((char *)h,p,(char *)n);
  170.   if (session == NULL) 
  171.   {
  172.     SessionCreationFailedException ex;
  173.     throw(ex);
  174.   }
  175. }
  176.  
  177. inline Session::~Session() throw()  
  178. {
  179.   (void)QFreeSession(session);
  180. }
  181.  
  182. inline struct MsgPort * Session::getMsgPort() const throw()
  183. {
  184.   return(session->qMsgPort);
  185. }
  186.     
  187. inline LONG Session::getOp(const char * wildpath, LONG maxBytes) throw()
  188. {
  189.   return(QGetOp(session, (char *)wildpath, maxBytes));
  190. }
  191.  
  192. inline LONG Session::setOp(const char * path, const void * buffer, ULONG bufferLength) throw()
  193. {
  194.   return(QSetOp(session, (char *)path, (void *)buffer, bufferLength));
  195. }
  196.  
  197. inline LONG Session::subscribeOp(const char * wildpath, LONG maxBytes) throw()
  198. {
  199.   return(QSubscribeOp(session, (char *)wildpath, maxBytes));
  200. }
  201.  
  202. inline LONG Session::clearSubscriptionsOp(LONG which) throw()
  203. {
  204.   return(QClearSubscriptionsOp(session, which));
  205. }
  206.  
  207. inline LONG Session::getAndSubscribeOp(const char * wildpath, LONG maxBytes) throw()
  208. {
  209.   return(QGetAndSubscribeOp(session, (char *)wildpath, maxBytes));
  210. }
  211.  
  212. inline LONG Session::streamOp(const char * path, const void * buffer, ULONG bufferLength) throw()  
  213. {
  214.   return(QStreamOp(session, (char *)path, (void *)buffer, bufferLength));
  215. }
  216.  
  217. inline LONG Session::messageOp(const char * hosts, const void * buffer, ULONG bufferLength) throw()
  218. {
  219.   return(QMessageOp(session, (char *)hosts, (void *)buffer, bufferLength));
  220. }
  221.  
  222. inline LONG Session::renameOp(const char * path, const char * label) throw()
  223. {
  224.   return(QRenameOp(session, (char *)path, (char *)label));
  225. }
  226.  
  227. inline LONG Session::deleteOp(const char * wildpath) throw()
  228. {
  229.   return(QDeleteOp(session, (char *)wildpath));
  230. }
  231.  
  232. inline LONG Session::pingOp() throw()
  233. {
  234.   return(QPingOp(session));
  235. }
  236.  
  237. inline LONG Session::infoOp() throw()
  238. {
  239.   return(QInfoOp(session));
  240. }
  241.  
  242. inline LONG Session::debugOp(const char * string) throw()
  243. {
  244.   return(QDebugOp(session, (char *)string));
  245. }
  246.  
  247. inline LONG Session::setAccessOp(const char * newAccess) throw()
  248. {
  249.   return(QSetAccessOp(session, (char *)newAccess));
  250. }
  251.  
  252. inline LONG Session::setMessageAccessOp(const char * newAccess, LONG maxBytes) throw()
  253. {
  254.   return(QSetMessageAccessOp(session, (char *)newAccess, maxBytes));
  255. }
  256.  
  257. inline LONG Session::requestPrivilegesOp(ULONG privBits) throw()
  258. {
  259.   return(QRequestPrivilegesOp(session, privBits));
  260. }
  261.  
  262. inline LONG Session::releasePrivilegesOp(ULONG privBits) throw()
  263. {
  264.   return(QReleasePrivilegesOp(session, privBits));
  265. }
  266.  
  267. inline LONG Session::killClientsOp(const char * hosts) throw()
  268. {
  269.   return(QKillClientsOp(session, (char *)hosts));
  270. }
  271.  
  272. inline LONG Session::setParameterOp(const char * paramName, const char * newValue) throw()
  273. {
  274.   return(QSetParameterOp(session, (char *)paramName, (char *)newValue));
  275. }
  276.  
  277. inline LONG Session::getParameterOp(const char * paramName) throw()
  278. {
  279.   return(QGetParameterOp(session, (char *)paramName));
  280. }
  281.  
  282. inline LONG Session::sysMessageOp(const char * hosts, const char * message) throw()
  283. {
  284.   return(QSysMessageOp(session, (char *)hosts, (char *)message));
  285. }
  286.  
  287. inline LONG Session::go(ULONG flags) throw()
  288. {
  289.   return(QGo(session, flags));
  290. }
  291.  
  292. inline void Session::freeQMessage(struct QMessage * qmsg) throw()
  293. {
  294.   FreeQMessage(session, qmsg);
  295. }
  296.  
  297. inline ULONG Session::getNumQueuedPackets() const throw()
  298. {
  299.   return(QNumQueuedPackets(session));
  300. }
  301.  
  302. inline ULONG Session::getNumQueuedBytes() const throw()
  303. {
  304.   return(QNumQueuedBytes(session));
  305. }
  306.  
  307. inline const char * Session::getErrorName(LONG error) throw()
  308. {
  309.   return(QErrorName(error));
  310. }
  311.  
  312. inline BOOL Session::detachSession(ULONG flags) throw()
  313. {
  314.   return(QDetachSession(session, flags));
  315. }
  316.  
  317. inline BOOL Session::reattachSession(ULONG flags) throw()
  318. {
  319.   return(QReattachSession(session, flags));
  320. }
  321.  
  322. #endif /* SESSION_H */
  323.